NAME¶

git-svn - Bidirectional operation between a Subversion repository and git

SYNOPSIS¶

git svn <command> [options] [arguments]

DESCRIPTION¶

git svn is a simple conduit for changesets between Subversion and git. It provides a bidirectional flow of changes between a Subversion and a git repository.

git svn can track a standard Subversion repository, following the common "trunk/branches/tags" layout, with the --stdlayout option. It can also follow branches and tags in any layout with the -T/-t/-b options (see options to init below, and also the clone command).

Once tracking a Subversion repository (with any of the above methods), the git repository can be updated from Subversion by the fetch command and Subversion updated from git by the dcommit command.

COMMANDS¶

init

fetch

config key: svn-remote.<name>.ignore-paths

--ignore-paths="^doc"

--ignore-paths="^[^/]+/(?:branches|tags)"

clone

rebase

dcommit

config key: svn-remote.<name>.commiturl
config key: svn.commiturl (overwrites all svn-remote.<name>.commiturl options)

branch

git config --get-all svn-remote.<name>.branches
git config --get-all svn-remote.<name>.tags

git config --get-all svn-remote.<name>.commiturl

tag

log

blame

find-rev

set-tree

create-ignore

show-ignore

mkdirs

commit-diff

info

proplist

propget

show-externals

gc

reset

    r1---r2---r3 remotes/git-svn


                \


                 A---B master

git svn reset -r2 -p
git svn fetch

    r1---r2´--r3´ remotes/git-svn


      \


       r2---r3---A---B master

git rebase --onto remotes/git-svn A^ master

    r1---r2´--r3´ remotes/git-svn


                \


                 A´--B´ master

OPTIONS¶

--shared[={false|true|umask|group|all|world|everybody}], --template=<template_directory>

-r <ARG>, --revision <ARG>

-, --stdin

--rmdir

config key: svn.rmdir

-e, --edit

config key: svn.edit

-l<num>, --find-copies-harder

config key: svn.l
config key: svn.findcopiesharder

-A<filename>, --authors-file=<filename>

        loginname = Joe User <user@example.com>

config key: svn.authorsfile

--authors-prog=<filename>

-q, --quiet

--repack[=<n>], --repack-flags=<flags>

config key: svn.repack
config key: svn.repackflags

-m, --merge, -s<strategy>, --strategy=<strategy>

-n, --dry-run

ADVANCED OPTIONS¶

-i<GIT_SVN_ID>, --id <GIT_SVN_ID>

-R<remote name>, --svn-remote <remote name>

--follow-parent

config key: svn.followparent

CONFIG FILE-ONLY OPTIONS¶

svn.noMetadata, svn-remote.<name>.noMetadata

svn.useSvmProps, svn-remote.<name>.useSvmProps

svn.useSvnsyncProps, svn-remote.<name>.useSvnsyncprops

svn-remote.<name>.rewriteRoot

svn-remote.<name>.rewriteUUID

svn.brokenSymlinkWorkaround

Since the noMetadata, rewriteRoot, rewriteUUID, useSvnsyncProps and useSvmProps options all affect the metadata generated and used by git svn; they must be set in the configuration file before any history is imported and these settings should never be changed once they are set.

Additionally, only one of these options can be used per svn-remote section because they affect the git-svn-id: metadata line, except for rewriteRoot and rewriteUUID which can be used together.

BASIC EXAMPLES¶

Tracking and contributing to the trunk of a Subversion-managed project:

# Clone a repo (like git clone):


        git svn clone http://svn.example.com/project/trunk
# Enter the newly cloned directory:


        cd trunk
# You should be on master branch, double-check with ´git branch´


        git branch
# Do some work and commit locally to git:


        git commit ...
# Something is committed to SVN, rebase your local changes against the
# latest changes in SVN:


        git svn rebase
# Now commit your changes (that were committed previously using git) to SVN,
# as well as automatically updating your working HEAD:


        git svn dcommit
# Append svn:ignore settings to the default git exclude file:


        git svn show-ignore >> .git/info/exclude

Tracking and contributing to an entire Subversion-managed project (complete with a trunk, tags and branches):

# Clone a repo (like git clone):


        git svn clone http://svn.example.com/project -T trunk -b branches -t tags
# View all branches and tags you have cloned:


        git branch -r
# Create a new branch in SVN


    git svn branch waldo
# Reset your master to trunk (or any other branch, replacing ´trunk´
# with the appropriate name):


        git reset --hard remotes/trunk
# You may only dcommit to one branch/tag/trunk at a time.  The usage
# of dcommit/rebase/show-ignore should be the same as above.

The initial git svn clone can be quite time-consuming (especially for large Subversion repositories). If multiple people (or one person with multiple machines) want to use git svn to interact with the same Subversion repository, you can do the initial git svn clone to a repository on a server and have each person clone that repository with git clone:

# Do the initial import on a server


        ssh server "cd /pub && git svn clone http://svn.example.com/project
# Clone locally - make sure the refs/remotes/ space matches the server


        mkdir project


        cd project


        git init


        git remote add origin server:/pub/project


        git config --add remote.origin.fetch ´+refs/remotes/*:refs/remotes/*´


        git fetch
# Create a local branch from one of the branches just fetched


        git checkout -b master FETCH_HEAD
# Initialize ´git svn´ locally (be sure to use the same URL and -T/-b/-t options as were used on server)


        git svn init http://svn.example.com/project
# Pull the latest changes from Subversion


        git svn rebase

REBASE VS. PULL/MERGE¶

Originally, git svn recommended that the remotes/git-svn branch be pulled or merged from. This is because the author favored git svn set-tree B to commit a single head rather than the git svn set-tree A..B notation to commit multiple commits.

If you use git svn set-tree A..B to commit several diffs and you do not have the latest remotes/git-svn merged into my-branch, you should use git svn rebase to update your work branch instead of git pull or git merge. pull/merge can cause non-linear history to be flattened when committing into SVN, which can lead to merge commits reversing previous commits in SVN.

DESIGN PHILOSOPHY¶

Merge tracking in Subversion is lacking and doing branched development with Subversion can be cumbersome as a result. While git svn can track copy history (including branches and tags) for repositories adopting a standard layout, it cannot yet represent merge history that happened inside git back upstream to SVN users. Therefore it is advised that users keep history as linear as possible inside git to ease compatibility with SVN (see the CAVEATS section below).

CAVEATS¶

For the sake of simplicity and interoperating with a less-capable system (SVN), it is recommended that all git svn users clone, fetch and dcommit directly from the SVN server, and avoid all git clone/pull/merge/push operations between git repositories and branches. The recommended method of exchanging code between git branches and users is git format-patch and git am, or just ´dcommit’ing to the SVN repository.

Running git merge or git pull is NOT recommended on a branch you plan to dcommit from. Subversion does not represent merges in any reasonable or useful fashion; so users using Subversion cannot see any merges you’ve made. Furthermore, if you merge or pull from a git branch that is a mirror of an SVN branch, dcommit may commit to the wrong branch.

If you do merge, note the following rule: git svn dcommit will attempt to commit on top of the SVN commit named in

git log --grep=^git-svn-id: --first-parent -1

You must therefore ensure that the most recent commit of the branch you want to dcommit to is the first parent of the merge. Chaos will ensue otherwise, especially if the first parent is an older commit on the same SVN branch.

git clone does not clone branches under the refs/remotes/ hierarchy or any git svn metadata, or config. So repositories created and managed with using git svn should use rsync for cloning, if cloning is to be done at all.

Since dcommit uses rebase internally, any git branches you git push to before dcommit on will require forcing an overwrite of the existing ref on the remote repository. This is generally considered bad practice, see the git-push(1) documentation for details.

Do not use the --amend option of git-commit(1) on a change you’ve already dcommitted. It is considered bad practice to --amend commits you’ve already pushed to a remote repository for other users, and dcommit with SVN is analogous to that.

When using multiple --branches or --tags, git svn does not automatically handle name collisions (for example, if two branches from different paths have the same name, or if a branch and a tag have the same name). In these cases, use init to set up your git repository then, before your first fetch, edit the .git/config file so that the branches and tags are associated with different name spaces. For example:

branches = stable/*:refs/remotes/svn/stable/*
branches = debug/*:refs/remotes/svn/debug/*

BUGS¶

We ignore all SVN properties except svn:executable. Any unhandled properties are logged to $GIT_DIR/svn/<refname>/unhandled.log

Renamed and copied directories are not detected by git and hence not tracked when committing to SVN. I do not plan on adding support for this as it’s quite difficult and time-consuming to get working for all the possible corner cases (git doesn’t do it, either). Committing renamed and copied files are fully supported if they’re similar enough for git to detect them.

CONFIGURATION¶

git svn stores [svn-remote] configuration information in the repository .git/config file. It is similar the core git [remote] sections except fetch keys do not accept glob arguments; but they are instead handled by the branches and tags keys. Since some SVN repositories are oddly configured with multiple projects glob expansions such those listed below are allowed:

[svn-remote "project-a"]


        url = http://server.org/svn


        fetch = trunk/project-a:refs/remotes/project-a/trunk


        branches = branches/*/project-a:refs/remotes/project-a/branches/*


        tags = tags/*/project-a:refs/remotes/project-a/tags/*

Keep in mind that the * (asterisk) wildcard of the local ref (right of the :) must be the farthest right path component; however the remote wildcard may be anywhere as long as it’s an independent path component (surrounded by / or EOL). This type of configuration is not automatically created by init and should be manually entered with a text-editor or using git config.

It is also possible to fetch a subset of branches or tags by using a comma-separated list of names within braces. For example:

[svn-remote "huge-project"]


        url = http://server.org/svn


        fetch = trunk/src:refs/remotes/trunk


        branches = branches/{red,green}/src:refs/remotes/branches/*


        tags = tags/{1.0,2.0}/src:refs/remotes/tags/*

Note that git-svn keeps track of the highest revision in which a branch or tag has appeared. If the subset of branches or tags is changed after fetching, then .git/svn/.metadata must be manually edited to remove (or reset) branches-maxRev and/or tags-maxRev as appropriate.

SEE ALSO¶

git-rebase(1)

AUTHOR¶

Written by Eric Wong <normalperson@yhbt.net[1]>.

DOCUMENTATION¶

Written by Eric Wong <normalperson@yhbt.net[1]>.

NOTES¶

1.

normalperson@yhbt.net